fix: restructure artifacts directory for $ref consumption by hdamker · Pull Request #606 · camaraproject/Commonalities

hdamker · 2026-03-30T18:20:17Z

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

Restructures the artifacts/ directory for $ref consumption and bundling (#603).

Phase 1 — common schemas:

Moves CAMARA_common.yaml to artifacts/common/, adds DateTime schema
Adds artifacts/api-templates/sample-service.yaml — CRUD template demonstrating $ref to common schemas

Phase 2 — event and subscription schemas:

Adds artifacts/common/CAMARA_event_common.yaml — CloudEvents envelope, subscription management, protocol settings, credentials, lifecycle data, and subscription-specific error responses
Adds artifacts/api-templates/sample-service-subscriptions.yaml — explicit subscription template rewritten with $ref (624 lines, down from 1397)
Adds artifacts/notification-templates/sample-notification.yaml — notification callback template with $ref (77 lines, down from 345)
Moves event-subscription-template.feature to artifacts/testing/
Removes notification-as-cloud-event.yaml and camara-cloudevents/ directory

Phase 3 — clean up unused protocol and credential definitions:

Comments out non-HTTP protocol support (MQTT3, MQTT5, AMQP, NATS, KAFKA) in both sample-service-subscriptions.yaml and CAMARA_event_common.yaml — only HTTP is used in CAMARA, comments signal future extensibility
Comments out PLAIN sink credential (enum, discriminator mapping, PlainCredential schema) — not used in CAMARA, only ACCESSTOKEN and PRIVATE_KEY_JWT are supported

Common files use a components-only format (no openapi/paths stub) — they are consumed via $ref, not deployed as standalone APIs.

Which issue(s) this PR fixes:

Fixes #603

Does this PR introduce a breaking change?

Yes
No

Special notes for reviewers:

Deferred: sample-implicit-events.yaml (callback-based event pattern template) — tracked as a follow-up issue.

All templates validated with redocly bundle (all $ref resolved) and spectral lint (no new errors). Phase 3 changes also validated on ReleaseTest#64 — bundled output contains only HTTP schemas and no PLAIN credential.

Changelog input

 release-note
fix: restructure artifacts directory for $ref consumption — common schemas, event/subscription schemas, and API templates

Additional documentation

docs
Updated README.md with new directory structure and file descriptions.

…ect#603) Phase 1 of artifacts restructuring: - Move CAMARA_common.yaml to artifacts/common/ directory - Add api-templates/sample-service.yaml demonstrating $ref consumption - Update documentation references to new path The sample-service template demonstrates two patterns for error responses: - Option A: pure $ref for responses using only generic error codes - Option B: local response definition extending generic errors with API-specific codes (ResourceNotFound404 example) Next steps (after camaraproject#604 merges): - Add CAMARA_event_common.yaml with CloudEvent/Source/DateTime schemas - Add notification-templates/sample-notification.yaml - Add event-related API templates (implicit events, subscriptions) - Migrate camara-cloudevents/ content to new structure

hdamker · 2026-03-30T18:47:51Z

Converted to draft as I have discussed with @rartych to add also the restructure of event related artifacts after
#604 is merged. Plan is to do that tomorrow.

…ifacts-v2

…onsumption - Add artifacts/common/CAMARA_event_common.yaml with CloudEvents envelope, subscription management, protocol settings, credentials, lifecycle data, and subscription-specific error responses - Add artifacts/api-templates/sample-service-subscriptions.yaml (624 lines, down from 1397 — 55% reduction via $ref to common files) - Add artifacts/notification-templates/sample-notification.yaml (77 lines, replacing 345-line notification-as-cloud-event.yaml) - Add DateTime schema to CAMARA_common.yaml - Switch common files to components-only format (no openapi/paths stub) - Move event-subscription-template.feature to artifacts/testing/ - Remove notification-as-cloud-event.yaml and camara-cloudevents/ directory - Update README.md with new directory structure

hdamker · 2026-03-31T12:59:26Z

Design note: boundary between `CAMARA_event_common.yaml` and `sample-service-subscriptions.yaml`

The restructuring extracts Commonalities-owned schemas into CAMARA_event_common.yaml so that API repositories can consume them via $ref. However, several schemas that are structurally Commonalities-owned remain in the subscription template. This is intentional.

What moved to `CAMARA_event_common.yaml`

Schemas that are identical across all APIs with no placeholders:

CloudEvents envelope: CloudEvent, Source (+ DateTime in CAMARA_common.yaml)
Subscription management: Config, CreateSubscriptionDetail, SubscriptionId
Protocol support: Protocol, HTTPSettings, MQTTSettings, AMQPSettings, ApacheKafkaSettings, NATSSettings
Credentials: SinkCredential, PlainCredential, AccessTokenCredential, PrivateKeyJWTCredential
Lifecycle data: SubscriptionStarted, SubscriptionUpdated, SubscriptionEnded, InitiationReason, UpdateReason, TerminationReason
Subscription error responses: CreateSubscriptionBadRequest400, SubscriptionIdRequired400, SubscriptionPermissionDenied403, CreateSubscriptionUnprocessableEntity422
Security schemes: notificationsBearerAuth (notification bearer auth)

What stays in the template — and why

Several schemas that look generic actually contain api-name placeholders in enum values or discriminator mappings. These must be adapted by each API project, so they cannot be consumed as-is via $ref:

SubscriptionRequest and Subscription — their types field references ApiEventType, which has api-name in its enum values
Protocol-specific Request/Response schemas (e.g., HTTPSubscriptionRequest) — extend SubscriptionRequest/Subscription via allOf
SubscriptionLifecycleEvent and SubscriptionLifecycleEventType — lifecycle event type strings contain api-name (e.g., org.camaraproject.api-name.v0.subscription-started)
EventSubscriptionStarted/Updated/Ended — extend SubscriptionLifecycleEvent
ApiNotificationEvent, ApiEventType, NotificationEvent, EventApiSpecific1/2 — API-specific by design

The root cause is that SubscriptionLifecycleEventType enum values embed the API name. A future discussion (see #604 review thread) may introduce a common naming pattern like org.camaraproject.subscription-event.v0.subscription-* which would allow moving these schemas to the common file as well.

- sample-service.yaml: title without "API", add externalDocs, fix apiRoot description, add pagination (minItems/maxItems), add maxLength to UUID - CAMARA_common.yaml: add description to openId securityScheme - sample-service-subscriptions.yaml: openId via $ref to CAMARA_common.yaml

hdamker · 2026-04-01T17:29:33Z

Thanks @rartych for the review! All suggestions applied in the latest push:

openId description in CAMARA_common.yaml: added description: OpenID Connect authentication via discovery metadata.
openId via $ref in sample-service-subscriptions.yaml: replaced inline definition with $ref: "../common/CAMARA_common.yaml#/components/securitySchemes/openId"
Pagination in sample-service.yaml list response: added minItems: 0, maxItems: 1000
ResourceId maxLength in sample-service.yaml: added maxLength: 36 for UUID format

Additional fixes found during Design Guide compliance check:

Title: removed "API" from title (Sample CAMARA Service API → Sample Service) — Design Guide 5.3.1: "title SHALL NOT include the term API"
externalDocs: added missing externalDocs object — Design Guide 5.4 (SHALL)
apiRoot description: fixed garbled text to match Design Guide 5.5 standard description

Comment out MQTT3, MQTT5, AMQP, NATS, KAFKA protocol references in both sample-service-subscriptions.yaml and CAMARA_event_common.yaml. Comments signal future extensibility; bundled output is now HTTP-only. Changes: - Protocol enum: converted to block sequence, only HTTP active - Discriminator mappings: only HTTP mapping active - Protocol-specific schemas: 8 non-HTTP schemas commented out - Settings schemas: MQTTSettings, AMQPSettings, ApacheKafkaSettings, NATSSettings commented out, HTTPSettings remains Validated on camaraproject/ReleaseTest#64 (bundling + yamllint + spectral).

…mon.yaml No api-name placeholders, identical across all subscription APIs. Template now uses $ref to common file, matching the openId pattern.

Comment out PLAIN enum value, discriminator mapping, and PlainCredential schema in CAMARA_event_common.yaml. The description already states that only ACCESSTOKEN and PRIVATE_KEY_JWT are supported.

tanjadegroot

redefine TimePeriod to use $ref to DateTime

Per review discussion — replace inline date-time definitions with $ref to the DateTime schema. Move endDate optionality note to the TimePeriod object description.

hdamker · 2026-04-07T10:32:40Z

redefine TimePeriod to use $ref to DateTime

@tanjadegroot Done in 9bbd0bf. Thanks for the final proposal, moving the description up was the solution.

Replace all functional api-name/apiName placeholders with concrete values matching the template filename, consistent with sample-service.yaml which already uses concrete names. This makes the template a valid, lintable OpenAPI spec. Replacements: - Event types: org.camaraproject.sample-service-subscriptions.v0.* - Server URL: sample-service-subscriptions/vwip - Security scopes: sample-service-subscriptions:* - Tags: Sample Service Subscription - operationIds: createSampleServiceSubscription etc. - Summaries/descriptions: sample service

Add Generic400 error responses to GET /resources, GET /resources/{resourceId}, and DELETE /resources/{resourceId}. POST /resources already had 400. Addresses OWASP API8 validation warning (define-error-validation).

PedroDiez

great work @hdamker!

Looks fine. Some minor suggestions and one clarification doubt.

I think also CAMARA-API-Event-Subscription-and-Notification-Guide.md needs to be updated regarding some links and file names, according to this artifacts refactor

E.g.:

Section 2.2. Resource-based (Explicit) Subscription ->

A generic neutral CloudEvent subscription OpenAPI specification is available in Commonalities/artifacts/camara-cloudevents directory (event-subscription-template.yaml).

…ifacts-v2

- Add backtick formatting for endDate in TimePeriod description - Add template usage clarification note to sample-service-subscriptions - Update 6 stale artifact path references in Event Subscription and Notification Guide to match restructured directory layout

hdamker · 2026-04-09T12:52:19Z

I think also CAMARA-API-Event-Subscription-and-Notification-Guide.md needs to be updated regarding some links and file names, according to this artifacts refactor

@PedroDiez done in 58a0902, please check if there are further occurrences.

PedroDiez · 2026-04-10T11:44:39Z

@hdamker One comment/observation I would like to make apart from the review.

In some of the artifacts, the are the same common references replicated N-times for different fields

As an example, in sample-service-subscriptions.yaml:

      parameters:
        - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"

Other way would be to define a "common local schema" in the file for x-correlator and that "common local schema" is referenced to the CAMARA_common.yaml x-correlator schema only once.

Maybe you have seen this way better for latter applying the bundling (just in case)

PedroDiez

LGTM in advance

Minor comment for wording aligment

hdamker · 2026-04-10T21:21:17Z

Other way would be to define a "common local schema" in the file for x-correlator and that "common local schema" is referenced to the CAMARA_common.yaml x-correlator schema only once.

@PedroDiez the bundling will do the deduplication. In the bundle there will be exactly one ("common") definition for the parameter x-correlator, and all references to it are replaced by file local references. You can see an example of the bundled API in https://github.com/camaraproject/ReleaseTest/actions/runs/24240183042/artifacts/6369710607

…uide.md

Adds sample-implicit-events.yaml under artifacts/api-templates/ as the canonical template for CAMARA APIs that deliver event notifications via OpenAPI callbacks on a resource-creation operation, with no dedicated /subscriptions sub-API (implicit-subscription pattern). Follows the post-camaraproject#604 layered event-schema architecture: pure CloudEvent envelope referenced from CAMARA_event_common.yaml, local ApiNotificationEvent that constrains type via ApiEventType and owns the discriminator mapping, concrete event schemas extending ApiNotificationEvent. Companion documentation update to CAMARA-API-Event-Subscription-and-Notification-Guide.md is deferred to a follow-up commit to avoid conflicts with camaraproject#606 doc edits.

hdamker · 2026-04-13T06:49:49Z

@camaraproject/commonalities_codeowners please consider to review and approve the PR upfront to todays meeting ... only after it landed in main I can finalize #612 and mark it ready for review.

cc: @tanjadegroot

patrice-conil

Nice job Herbert!
LGTM

PedroDiez · 2026-04-13T07:44:06Z

@PedroDiez the bundling will do the deduplication. In the bundle there will be exactly one ("common") definition for the parameter x-correlator, and all references to it are replaced by file local references. You can see an example of the bundled API in https://github.com/camaraproject/ReleaseTest/actions/runs/24240183042/artifacts/6369710607

thanks for the info @hdamker!

PedroDiez

LGTM

rartych

LGTM

hdamker requested review from PedroDiez, eric-murray, jlurien, patrice-conil and rartych as code owners March 30, 2026 18:20

hdamker marked this pull request as draft March 30, 2026 18:46

hdamker mentioned this pull request Mar 30, 2026

fix: restructure artifacts directory for $ref consumption hdamker/Commonalities#2

Closed

2 tasks

hdamker added 2 commits March 31, 2026 13:34

Merge remote-tracking branch 'upstream/main' into fix/restructure-art…

b674663

…ifacts-v2

hdamker mentioned this pull request Mar 31, 2026

Add sample-implicit-events.yaml API template for callback-based event pattern #608

Closed

fix: update stale template reference in feature file comment

7494d0c

rartych reviewed Apr 1, 2026

View reviewed changes

Comment thread artifacts/common/CAMARA_common.yaml

rartych reviewed Apr 1, 2026

View reviewed changes

Comment thread artifacts/api-templates/sample-service-subscriptions.yaml Outdated

rartych reviewed Apr 1, 2026

View reviewed changes

Comment thread artifacts/api-templates/sample-service.yaml

rartych reviewed Apr 1, 2026

View reviewed changes

Comment thread artifacts/api-templates/sample-service.yaml

This was referenced Apr 1, 2026

fix: align API definitions with Design Guide and Commonalities artifacts camaraproject/ReleaseTest#62

Merged

feat: add sample-service-subscriptions API definition camaraproject/ReleaseTest#63

Merged

fix: remove trailing blank line in sample-service-subscriptions.yaml

7ca2f60

hdamker mentioned this pull request Apr 2, 2026

fix: comment out non-HTTP protocol support (not yet used in CAMARA) camaraproject/ReleaseTest#64

Merged

hdamker added 3 commits April 2, 2026 15:37

fix: move notificationsBearerAuth security scheme to CAMARA_event_com…

0061276

…mon.yaml No api-name placeholders, identical across all subscription APIs. Template now uses $ref to common file, matching the openId pattern.

fix: comment out PLAIN sink credential (not used in CAMARA)

267cd79

Comment out PLAIN enum value, discriminator mapping, and PlainCredential schema in CAMARA_event_common.yaml. The description already states that only ACCESSTOKEN and PRIVATE_KEY_JWT are supported.

hdamker-bot marked this pull request as ready for review April 2, 2026 14:00

rartych self-requested a review April 3, 2026 13:53

hdamker commented Apr 3, 2026

View reviewed changes

Comment thread artifacts/api-templates/sample-service-subscriptions.yaml Outdated

tanjadegroot reviewed Apr 7, 2026

View reviewed changes

Comment thread artifacts/common/CAMARA_common.yaml

tanjadegroot reviewed Apr 7, 2026

View reviewed changes

fix: simplify TimePeriod to use $ref to DateTime schema

9bbd0bf

Per review discussion — replace inline date-time definitions with $ref to the DateTime schema. Move endDate optionality note to the TimePeriod object description.

hdamker added 2 commits April 7, 2026 16:55

fix: add 400 error responses to sample-service template operations

1d702d2

Add Generic400 error responses to GET /resources, GET /resources/{resourceId}, and DELETE /resources/{resourceId}. POST /resources already had 400. Addresses OWASP API8 validation warning (define-error-validation).

hdamker mentioned this pull request Apr 7, 2026

fix: align common files and templates with Commonalities #606 camaraproject/ReleaseTest#67

Merged

rartych requested a review from tanjadegroot April 8, 2026 11:45

PedroDiez reviewed Apr 8, 2026

View reviewed changes

Comment thread artifacts/common/CAMARA_common.yaml Outdated

Comment thread artifacts/common/CAMARA_event_common.yaml

Comment thread artifacts/api-templates/sample-service-subscriptions.yaml

PedroDiez mentioned this pull request Apr 8, 2026

Refactor Invalid Token Context Error #607

Merged

2 tasks

hdamker added 2 commits April 9, 2026 14:45

Merge remote-tracking branch 'upstream/main' into fix/restructure-art…

845e53a

…ifacts-v2

PedroDiez previously approved these changes Apr 10, 2026

View reviewed changes

Comment thread documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md Outdated

Update documentation/CAMARA-API-Event-Subscription-and-Notification-G…

7fa2cc3

…uide.md

hdamker dismissed PedroDiez’s stale review via 7fa2cc3 April 11, 2026 05:18

hdamker mentioned this pull request Apr 11, 2026

feat: add implicit-subscription API template #612

Merged

2 tasks

hdamker requested a review from PedroDiez April 13, 2026 06:46

patrice-conil approved these changes Apr 13, 2026

View reviewed changes

PedroDiez approved these changes Apr 13, 2026

View reviewed changes

rartych approved these changes Apr 13, 2026

View reviewed changes

rartych merged commit fcbc9a0 into camaraproject:main Apr 13, 2026
1 check passed

This was referenced Apr 13, 2026

HTTPSettings.headers in CAMARA_event_common.yaml: remove or constrain? #615

Open

New guidelines for OWASP API Security Top 10 too restricted (or lack guidelines) #596

Open

hdamker deleted the fix/restructure-artifacts-v2 branch April 13, 2026 20:24

Conversation

hdamker commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What type of PR is this?

What this PR does / why we need it:

Which issue(s) this PR fixes:

Does this PR introduce a breaking change?

Special notes for reviewers:

Changelog input

Additional documentation

Uh oh!

hdamker commented Mar 30, 2026

Uh oh!

hdamker commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Design note: boundary between CAMARA_event_common.yaml and sample-service-subscriptions.yaml

What moved to CAMARA_event_common.yaml

What stays in the template — and why

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hdamker commented Apr 1, 2026

Uh oh!

Uh oh!

Uh oh!

tanjadegroot left a comment

Choose a reason for hiding this comment

Uh oh!

hdamker commented Apr 7, 2026

Uh oh!

PedroDiez left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hdamker commented Apr 9, 2026

Uh oh!

PedroDiez commented Apr 10, 2026

Uh oh!

PedroDiez left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hdamker commented Apr 10, 2026

Uh oh!

hdamker commented Apr 13, 2026

Uh oh!

patrice-conil left a comment

Choose a reason for hiding this comment

Uh oh!

PedroDiez commented Apr 13, 2026

Uh oh!

PedroDiez left a comment

Choose a reason for hiding this comment

Uh oh!

rartych left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hdamker commented Mar 30, 2026 •

edited

Loading

hdamker commented Mar 31, 2026 •

edited

Loading

Design note: boundary between `CAMARA_event_common.yaml` and `sample-service-subscriptions.yaml`

What moved to `CAMARA_event_common.yaml`

PedroDiez left a comment •

edited

Loading